ParcelLabel API

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcellabel/v3/labels

Production:

https://api.nzpost.co.nz/parcellabel/v3/labels

Resource Description

Request for creating Dangerous Goods labels which are to be delivered within New Zealand. These labels are returned in either a PDF or PNG format.

Resource Information

Request Parameters

A unique consignment_id is returned once the details of the request are stored in the labeling database. One or multiple labels can be generated within a domestic consignment.

All fields that are not applicable to the request will not be validated and will be ignored.

If the pickup and delivery country_codes are both NZ then the request is considered to be for a domestic label. Else, the request is considered to be for an international label.

Please note that all request and response parameter Field Names must be in lower case.

Field Name	Description	Required
carrier	Carrier of the parcel. Value must be one of COURIERPOST OR PACE	Yes
orientation	Print orientation of the label. Value must be PORTRAIT or LANDSCAPE. Default value is LANDSCAPE.	No
logo_id	Unique identifier for merchants logo. The field is only relevant for COURIERPOST and PACE	No
notification_endpoint	Merchants Webhook URL to receive notification when the label has been generated. See Webhook Usage below.	No
sender_reference_1	Sender's reference for the consignment. Will be printed on the label.	No
sender_reference_2	Sender's reference (e.g. cost centre number for CP manifesting). Will not be printed on the label.	No
account_number	Your NZ Post Billing Account number (9 or 5 series).This is highly recommended to pass in the API call to obtain your account rates.	No
despatch_date	Required field for CPOLPSED service - notifies of date that the parcel should be picked up and delivered. Format is DD/MM/YY	No
job_number	Pace Job Booking Number. Used to generate the tracking number for the label. This field is only relevant for PACE.	Yes if carrier is PACE
label_dimensions	An object specifying the label dimensions (in mm) upon which to print the label. If you are passing this object then the value should be 150x100 or 174x100 or empty string. If it is empty then default value is 174x100. This field is only mandatory to generate 150x100 dimensions label.	No
paper_dimensions	An object containing the paper size upon which to print the label. See Paper Dimension Object Parameters section.	No
paper_dimensions.width_cm	Width the label to be printed to. Default value is 17.4. Note: To print on a 150x100 label this value must be set to ‘15.0’	No
paper_dimensions.height_cm	Height of the label to be printed to. Default value is 10	No
paper_dimensions.stationery_size	Paper size upon which to print the label. Must be A4 or A5.	No
sender_details	An object containing the sender contact details. See Sender Details Object Parameters below.	Yes
sender_details.name	Name of the sender.	Yes
sender_details.phone	Phone number of the sender. NO SPACES, DIGITS ONLY	No but highly desirable
sender_details.site_code	Site code assigned to the address where the parcel will be picked up by the courier. This address is also used for the NZ Post manifest process.	Yes
sender_details.company_name	Company name of the sender.	No
sender_details.email	Email address of the sender.	No
sender_details.freepost_number	FreePost number of the sender. This field is for ParcelPost Domestic Return labels.	No
receiver_details	An object containing the receiver contact details. See Receiver Details Object Parameters below.	Yes
receiver_details.name	Name of the receiver.	Yes
receiver_details.phone	Contact phone number of the receiver. NO SPACES, DIGITS ONLY	No but highly desirable
receiver_details.email	Email address of the receiver.	No but highly desirable
pickup_address	An object containing the sender pickup address details. See Pickup Address parameters below	Yes
Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes.
pickup_address.address_id	Address ID for the pickup address sourced from the ParcelAddress API.	See pickup_address rules
pickup_address.dpid	Delivery Point ID for the pickup address sourced from the ParcelAddress API.	See pickup_address rules
pickup_address.site_code	Site code of the pickup address.	See pickup_address rules
pickup_address.street	Street name of the pickup address.	See pickup_address rules
pickup_address.suburb	Suburb of the pickup address	See pickup_address rules
pickup_address.city	City of the pickup address	See pickup_address rules
pickup_address.postcode	Postal or zip code of the pickup address.	See pickup_address rules
pickup_address.unit_type	Type of unit (if applicable) of the pickup address.	No
pickup_address.unit_value	Value of the unit type.	Yes if pickup_address.unit_type is not blank
pickup_address.floor	Floor of the pickup address.	No
pickup_address.country_code	Two character country code of the pickup address. For domestic labels, this must be set to NZ.	Yes
pickup_address.company_name	Company name of the pickup address	No
pickup_address.building_name	Building name of the pickup address.	No
pickup_address.lobby_location	An object containing PO Box or Private Bag details of the parcel to be returned to. This object is for ParcelPost Domestic Return labels only. See Pickup Address - Lobby Location Object Parameters.	No
pickup_address.lobby_location.type	Location type of the return address. Value must be one of: POBOX, PRIVATEBAG.	Yes
pickup_address.lobby_location.number	Private Bag number or the PO Box number of the parcel to be returned to. This field is for ParcelPost Domestic Return labels.	Yes
pickup_address.lobby_location.city	City of the return address	Yes
pickup_address.lobby_location.postcode	Postcode of the return address	Yes
pickup_address.lobby_location.name	Name of the recipient.	No
pickup_address.lobby_location.lobby	Lobby name of the return address.	No
delivery_address	An object containing the receiver delivery address details. See Delivery Address Object Parameters below.	Yes
delivery_address rules: country_code (mandatory) AND: only one of the following is required: address_id (highly desirable) OR dpid (highly desirable) OR site_code OR street, suburb, city, and postcode. Use the city for addresses without suburbs.	Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes.
delivery_address.address_id	Address ID for the delivery address sourced from the ParcelAddress API.	See delivery_address rules
delivery_address.dpid	Numeric Delivery Point Identifier for the delivery sourced from the ParcelAddress API.	See delivery_address rules
delivery_address.site_code	Site code of the pickup address.	See delivery_address rules
delivery_address.street	Street name of the pickup address.	See delivery_address rules
delivery_address.suburb	Suburb of the pickup address	See delivery_address rules
delivery_address.city	City of the pickup address	See delivery_address rules
delivery_address.postcode	Postal or zip code of the pickup address.	See delivery_address rules
delivery_address.unit_type	Type of unit (if applicable) of the pickup address.	No
delivery_address.unit_value	Value of the unit type.	Yes if delivery_address.unit_type is not blank
delivery_address.floor	Floor of the pickup address.	No
delivery_address.country_code	Two character country code of the pickup address. For domestic labels, this must be set to NZ.	Yes
delivery_address.company_name	Name of company that the parcel is being delivered to.	No
delivery_address.building_name	Building name of the delivery address.	No
delivery_address.instructions	Delivery instructions for courier	No
delivery_address.is_collection	Whether the delivery address is a NZ Post collection point. Default value is false.	No
parcel_details	An array containing the label details for each label in the consignment. See Parcel Details Object Parameters section	Yes
parcel_details.service_code	Code to represent a delivery service. For international labels, this is the NetDespatch service code. For domestic labels where carrier is COURIERPOST and the parcel is a Trackpak, see rules in the Envelope Sizes section.	Yes
parcel_details.add_ons	Array of ancillary codes. This field is only relevant for COURIERPOST. Valid addons are: CPSR, CPOLRD, CPOLOED, CPOLSED, CPOLSAT, CPOLDG. Please refer to the Add ons section below for further details.	No
parcel_details.return_indicator	Indications if the label is used for returning items. Values must be OUTBOUND or RETURN. This field is only relevant for COURIERPOST.	Yes if carrier is COURIERPOST
parcel_details.description	The box size name on the label for the dispatching person to choose the correct box for packing. This value is relevant only for PACE and COURIERPOST.	No
parcel_details.dimensions	An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section.	Yes
parcel_details.dimension rules: for courierpost/pace labels that aren't courierpost trackpaks only one of the following is required: length_cm, width_cm, and height_cm OR length_cm and diameter_cm OR volume_m3 (highly desirable - only an option if carrier is Courierpost)
parcel_details.dimensions.length_cm	Length of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.width_cm	Width of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.height_cm	Height of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.diameter_cm	Diameter of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.volume_m3	Volume of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.weight_kg	Physical weight of the parcel in kilograms.	Yes if not a COURIERPOST Trackpak
parcel_details.dangerous_goods	An object containing the dangerous goods details of a parcel. Note: If this object is present in the incoming request, addOn must be CPOLDG otherwise validation error will be returned.	No
parcel_details.dangerous_goods.items	An array containing the dangerous goods items details of a parcel. Maximum 3 items.	No
parcel_details.dangerous_goods.items.un_number	The dangerous goods item unique identifier number. Must be a four digit number or four digit number starts with UN. Ex. 3481 or UN3481	No
parcel_details.dangerous_goods.items.hazard_class	The dangerous goods item hazard class indicator. Must be one of these: 9 or 9.1 or 9(9) or 9(9.1)	No
parcel_details.dangerous_goods.items.proper_shipping_name	The dangerous goods item shipping name. Ex. Environmentally hazardous substance, liquid, n.o.s. (Amicarbazone, Propylene glycol)	No
parcel_details.dangerous_goods.items.packing_group	The Dangerous goods item packing group number. Must be one of these: I or II or III or na or n/a or NA or N/A	No
parcel_details.dangerous_goods.items.number_and_type_packages	The Dangerous goods item packgage type. Ex. 2x Steel Drum	No
parcel_details.dangerous_goods.items.dg_weight	The dangerous goods item weight. Ex. 2kg	No
parcel_details.dangerous_goods.is_dglq	Items are DGLQ. Boolean type	No
parcel_details.dangerous_goods.is_radioactive	Is dangerous goods item radioactive? Ex. true or false	No
parcel_details.dangerous_goods.flashpoint	Flashpoints for each item in declaration. Ex. a)22 b)45 c)32	No
parcel_details.dangerous_goods.hazchem_code	hazchem_code for each item in declaration. Ex. a)2YE b)3YE c)2Y	No
parcel_details.dangerous_goods.is_marine_pollutant	marine_pollutant for each item in declaration. Ex. a)Yes b)No c)Yes	No
parcel_details.dangerous_goods.additional_information	Additional information	No
parcel_details.dangerous_goods.signatory_name	Sender Name	No
parcel_details.dangerous_goods.signatory_emergency_phone_number	Emergency telephone number. Ex. 100	No

• Validations

Dangerous Goods Validations	Validation results
Dangerous_Goods(DG) not provided and add_ons is CPOLDG in label request, then continue 'regular' label and empty dangerous goods form generation.	Label and DG form Generated.
Dangerous_Goods(DG) provided, but add_ons is not CPOLDG, then return an error message.	Error message: "There has been an error processing your request. Dangerous Goods AddOn not provided. Please contact support."
Dangerous_Goods(DG) provided and invalid un_number provided, then return an error message.	Error message: "Invalid UN Number".
Dangerous_Goods(DG) provided and invalid hazard_class provided, then return an error message.	Error message: "Invalid hazard class".
Dangerous_Goods(DG) provided and invalid packing_group provided, then return an error message.	Error message: "Packing group must be one of these values: 'I, II, III, na, NA, n/a, N/A".
Dangerous_Goods(DG) provided and Dangerous_Goods(DG).items array contains more than 3 objects, then return an error message.	Error message: "Number of DG Items Limit Exceeded".

Sample Request

{
    "account_number": "91327067",
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "Jason",
    "sender_reference_2": "CC 52",
    "paper_dimensions": {
        "width_cm": 17.4,
        "height_cm": 10,
        "stationery_size": "A4"
    },
    "sender_details": {
        "name": "John Doe",
        "xphone": "1",
        "email": "testsender@nzpost.co.nz",
        "company_name": "Acme Corp",
        "site_code": 96306
    },
    "pickup_address": {
        "country_code": "NZ",
        "address_id": 1945196
    },
    "receiver_details": {
        "name": "Joe Receiver",
        "xphone": "6490000002",
        "email": "testreceiver@nzpost.co.nz"
    },
    "delivery_address": {
        "is_collection": false,
        "building_name": "Test Delivery Building Name",
        "company_name": "Test Delivery Company Name",
        "street": "204 Blueskin Road",
        "suburb": "Brunswick",
        "city": "Whanganui",
        "country_code": "NZ",
        "postcode": "4571",
        "instructions": "Ask for John Smith at the reception."
    },
    "parcel_details": [
        {
            "service_code": "CPOLP",
            "add_ons": [
                "CPSR",
                "CPOLDG"
            ],
            "dangerous_goods": {
                "items": [
                    {
                        "un_number": "3082",
                        "hazard_class": "9",
                        "proper_shipping_name": "Environmentally hazardous substance, liquid, n.o.s. (Amicarbazone, Propylene glycol)",
                        "packing_group": "III",
                        "number_and_type_packages": "3 x Plastic Jerricans",
                        "dg_weight": "64"
                    },
                    {
                        "un_number": "UN1993",
                        "hazard_class": "3",
                        "proper_shipping_name": "Flammable Liquid, n.o.s. (Benzene, 1,2,4-trimethyl)",
                        "packing_group": "III",
                        "number_and_type_packages": "3 x Plastic Jerricans",
                        "dg_weight": "21"
                    },
                    {
                        "un_number": "UN1950",
                        "hazard_class": "2.1",
                        "proper_shipping_name": "Aerosols",
                        "packing_group": "NA",
                        "number_and_type_packages": "1 x Fibreboard Box",
                        "dg_weight": "5"
                    }
                ],
                "is_dglq": true,
                "is_radioactive": false,
                "flashpoint": "34",
                "hazchem_code": "3YE",
                "is_marine_pollutant": "Yes",
                "additional_handling_information": "test additional handling information",
                "signatory_name": "Test signatory name",
                "signatory_emergency_phone_number": "111"
            },
            "return_indicator": "OUTBOUND",
            "description": "LARGE",
            "dimensions": {
                "length_cm": 5.8,
                "width_cm": 3,
                "height_cm": 5.0,
                "weight_kg": 3
            }
        }
    ]
}

Response Parameters

Field Name	Description	Mandatory
consignment_id	Unique identifier for the consignment if the request is successful.	Yes
message_id	A unique ID for the API call	Yes
success	Returns true if request is successful. Returns false if request is not successful.	Yes

Sample Response

{
  "consignment_id": "S3BGUH",
  "message_id": "bb590940-97b5-11e9-813b-02168927813a",
  "success": true
}

Resource URL

UAT:

Download Dangerous Goods declaration within a consignment:

https://api.uat.nzpost.co.nz/ParcelLabel/v3/labels/{consignment_id}/DG/{parcel_no}

Production:

Download Dangerous Goods declaration within a consignment:

https://api.nzpost.co.nz/ParcelLabel/v3/labels/{consignment_id}/DG/{parcel_no}

Resource Description

To download a Dangerous Goods Form generated form within a consignment, set parcel_number parameter to the parcel number of the label. Dangerous Goods forms are only available for download of a consignment with status "Complete". Use Get Status of Labels resource to check the status of the consignment prior to download.

Resource Information

Request Parameters

Sample Requests

Download a Dangerous Goods form generated within a consignment:

https://api.uat.nzpost.co.nz/ParcelLabel/v3/labels/6CW65J/DG/1

Response

The Dangerous Goods form is returned in PDF.

Sample Response

Sample: Failure

{
    "success": false,
    "errors": [
        {
            "code": "40000",
            "message": "Bad Request",
            "details": "No DG Form Available"
        }
    ],
    "message_id": "fbfaf950-e8ad-11ef-8d86-020d66982371"
}